.TH "frovedis::colmajor_matrix<T>" "" "" "" ""
.SH NAME
.PP
\f[C]frovedis::colmajor_matrix<T>\f[] \- A distributed two\-dimensional
dense matrix with elements stored in column\-wise order supported by
frovedis
.SH SYNOPSIS
.PP
\f[C]#include\ <frovedis/matrix/colmajor_matrix.hpp>\f[]
.SS Constructors
.PP
colmajor_matrix ();
.PD 0
.P
.PD
colmajor_matrix
(\f[C]frovedis::node_local<colmajor_matrix_local<T>>\f[]&& data);
.PD 0
.P
.PD
colmajor_matrix (const \f[C]rowmajor_matrix<T>\f[]& m);
.SS Public Member Functions
.PP
void debug_print ();
.PD 0
.P
.PD
\f[C]rowmajor_matrix<T>\f[] to_rowmajor();
.PD 0
.P
.PD
\f[C]rowmajor_matrix<T>\f[] moveto_rowmajor();
.SS Public Data Members
.PP
\f[C]frovedis::node_local<colmajor_matrix_local<T>>\f[] data
.PD 0
.P
.PD
size_t num_row
.PD 0
.P
.PD
size_t num_col
.SH DESCRIPTION
.PP
\f[C]colmajor_matrix<T>\f[] is a template based two\-dimensional dense
matrix with elements stored in column\-major order and distributed among
the participating worker nodes in row\-wise.
.PP
A \f[C]colmajor_matrix<T>\f[] contains public member "data" of the type
\f[C]node_local<colmajor_matrix_local<T>>\f[].
The actual distributed matrices are contained in all the worker nodes
locally, thus named as \f[C]colmajor_matrix_local<T>\f[] (see manual of
colmajor_matrix_local) and "data" is the reference to these local
matrices at worker nodes.
It also contains dimension information related to the global matrix
i.e., number of rows and number of columns in the original matrix.
.IP
.nf
\f[C]
template\ <class\ T>
struct\ colmajor_matrix\ {
\ \ frovedis::node_local<colmajor_matrix_local<T>>\ data;\ //\ local\ matrix\ information
\ \ size_t\ num_row;\ \ //\ number\ of\ rows\ in\ global\ matrix
\ \ size_t\ num_col;\ \ //\ number\ of\ columns\ in\ global\ matrix
};
\f[]
.fi
.PP
For example, if the below column\-major matrix with 4 rows and 4 columns
is distributed over two worker nodes, then the distribution can be shown
as:
.IP
.nf
\f[C]
1\ 5\ 8\ 4
2\ 6\ 7\ 3
3\ 7\ 6\ 2
4\ 8\ 5\ 1

master\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ worker0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ worker1
\-\-\-\-\-\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-\-\-\-\-\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-\-\-\-\-
colmajor_matrix<int>\ \ \ \ \ \ \ \->\ colmajor_matrix\ \ \ \ \ \ \ \ \ \ \ \ \ \->\ colmajor_matrix
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ _local<int>\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ _local<int>
\ \ \ *data:\ node_local<\ \ \ \ \ \ \ \ \ \ \ \ val:\ vector<int>\ \ \ \ \ \ \ \ \ \ \ \ \ val:\ vector<int>
\ \ \ \ \ \ \ \ \ colmajor_matrix\ \ \ \ \ \ \ \ \ \ \ \ \ ({1,5,8,4,\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ({3,7,6,2,
\ \ \ \ \ \ \ \ \ _local<int>>\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2,6,7,3})\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4,8,5,1})
\ \ \ \ num_row:\ size_t\ (4)\ \ \ \ \ \ \ \ \ \ local_num_row:\ size_t\ (2)\ \ \ \ local_num_row:\ size_t\ (2)
\ \ \ \ num_col:\ size_t\ (4)\ \ \ \ \ \ \ \ \ \ local_num_col:\ size_t\ (2)\ \ \ \ local_num_col:\ size_t\ (2)
\f[]
.fi
.PP
The \f[C]node_local<colmajor_matrix_local<int>>\f[] object "data" is
simply a (*)handle of the (\->)local matrices at worker nodes.
.PP
A distributed colmajor_matrix can be created from a distributed
rowmajor_matrix object and it can be converted back to the
rowmajor_matrix object.
Thus loading from file, saving into file etc.
interfaces are not provided for colmajor_matrix structure.
User may like to perform the conversion from/to rowmajor_matrix
structure for the same.
.SS Constructor Documentation
.SS colmajor_matrix ()
.PP
This is the default constructor which creates an empty distributed
colmajor matrix without any memory allocation at worker nodes.
.SS colmajor_matrix(const \f[C]rowmajor_matrix<T>\f[]& m)
.PP
It accepts a distributed \f[C]rowmajor_matrix<T>\f[] object with
elements stored in row\-major order and constructs an equivalent
distributed colmajor storage of same number of rows and columns.
Input row\-major storage remains unchanged.
.SS colmajor_matrix
(\f[C]frovedis::node_local<colmajor_matrix_local<T>>\f[]&& data)
.PP
This is the parameterized constructor which accepts an rvalue of the
type \f[C]node_local<colmajor_matrix_local<T>>\f[] and \f[I]moves\f[]
the contents to the created colmajor matrix.
.PP
In general, this constructor is used internally by some other functions.
But user may need this constructor while constructing their own colmajor
matrix using the return value of some function (returning a
\f[C]colmajor_matrix_local<T>\f[]) called using
"frovedis::node_local::map" (thus returned value would be an object of
type \f[C]node_local<colmajor_matrix_local<T>\f[]).
.PP
For example,
.IP
.nf
\f[C]
//\ \-\-\-\ a\ sample\ functor\ definition\ \-\-\-\ 
struct\ foo\ {
\ \ foo()\ {}
\ \ foo(int\ r,\ int\ c):\ nrow(r),\ ncol(c)\ {}
\ \ colmajor_matrix_local<int>\ operator()(std::vector<int>&\ v)\ {
\ \ \ \ colmajor_matrix_local<int>\ ret;
\ \ \ \ ret.val.swap(v);
\ \ \ \ ret.local_num_row\ =\ nrow;
\ \ \ \ ret.local_num_col\ =\ ncol;
\ \ \ \ return\ ret;
\ \ }
\ \ size_t\ nrow,\ ncol;
\ \ SERIALIZE(nrow,\ ncol)
};

size_t\ sum(size_t\ x,\ size_t\ y)\ {\ return\ x\ +\ y;\ }
size_t\ get_nrows(colmajor_matrix_local<int>&\ m)\ {\ return\ m.local_num_row;\ }
size_t\ get_ncols(colmajor_matrix_local<int>&\ m)\ {\ return\ m.local_num_col;\ }

std::vector<int>\ v\ =\ {1,3,5,7,2,4,6,8};\ //\ 4X2\ col\-major\ storage
auto\ bv\ =\ broadcast(v);
//\ demo\ of\ such\ a\ constructor\ call
colmajor_matrix<int>\ m(bv.map<colmajor_matrix_local<int>>(foo(4,2)));\ //\ m:\ 8x2\ matrix
//\ getting\ total\ number\ of\ rows\ in\ the\ global\ matrix
m.num_row\ =\ m.data.map(get_nrows).reduce(sum);\ //\ 4+4\ =\ 8
m.num_col\ =\ m.data.map(get_ncols).get(0);\ \ \ \ \ \ //\ 2
\f[]
.fi
.PP
The above program will perform the below tasks in order
.IP \[bu] 2
broadcast a vector containing sample elements of a 4x2
colmajor_matrix_local.
.PD 0
.P
.PD
.IP \[bu] 2
local colmajor matrices will be created in worker nodes when the functor
would be called.
.PD 0
.P
.PD
.IP \[bu] 2
"\f[C]bv.map<colmajor_matrix_local<int>>(foo(4,2))\f[]" will return a
\f[C]node_local<colmajor_matrix_local<int>\f[] object.
.PD 0
.P
.PD
.IP \[bu] 2
the constructor call will be made for colmajor_matrix passing the above
rvalue node_local object.
.IP \[bu] 2
total number of rows will be set by summing local_num_row of all worker
matrices.
.IP \[bu] 2
total number of columns will be set as per the number of columns in the
worker0 matrix (from any worker will be fine).
.SS Public Member Function Documentation
.SS void debug_print ()
.PP
It prints the contents and other information of the local matrices
node\-by\-node on the user terminal.
It is mainly useful for debugging purpose.
.PP
For example, if there are two worker nodes, then
.IP
.nf
\f[C]
std::vector<int>\ v\ =\ {1,2,3,4,5,6,7,8};\ //\ 4x2\ col\-major\ storage
rowmajor_matrix_local<int>\ m;
m.val.swap(v);
m.set_local_num(nrow,ncol);
//\ scattering\ local\ matrix\ to\ create\ the\ distributed\ rowmajor\ matrix
auto\ rm\ =\ make_rowmajor_matrix_scatter(m));
colmajor_matrix<int>\ cm(rm);\ //\ rowmajor_matrix\ =>\ colmajor_matrix
cm.debug_print();\ 
\f[]
.fi
.PP
The above program will output (order of display might differ):
.IP
.nf
\f[C]
node\ =\ 0,\ local_num_row\ =\ 2,\ local_num_col\ =\ 2,\ val\ =\ 1\ 3\ 2\ 4\ 
node\ =\ 1,\ local_num_row\ =\ 2,\ local_num_col\ =\ 2,\ val\ =\ 5\ 7\ 6\ 8
\f[]
.fi
.SS \f[C]rowmajor_matrix<T>\f[] to_rowmajor();
.PP
It converts the colmajor storage of the target distributed matrix to a
distributed rowmajor storage and returns the output
\f[C]rowmajor_matrix<T>\f[] after successful conversion.
The target colmajor storage remains unchanged after the conversion.
.SS \f[C]rowmajor_matrix<T>\f[] moveto_rowmajor();
.PP
If the target distributed column major matrix has only a single column,
then rowmajor storage and column major storage both will be the same.
Thus instead of any conversion overhead, elements in target matrix can
simply be moved while creating the rowmajor_matrix object.
It is faster and recommended, only when the target matrix is no longer
be needed in a user program.
.SS Public Data Member Documentation
.SS data
.PP
An instance of \f[C]node_local<colmajor_matrix_local<T>>\f[] type to
contain the reference information related to local matrices at worker
nodes.
.SS num_row
.PP
A size_t attribute to contain the total number of rows in the 2D matrix
view.
.SS num_col
.PP
A size_t attribute to contain the total number of columns in the 2D
matrix view.
.SH SEE ALSO
.PP
colmajor_matrix_local, rowmajor_matrix, blockcyclic_matrix
